Skip to main content
Version: 9.2

Methods and Events

The Dashboard widget supports two main interaction patterns: Direct Method Calls using the executeAction method and Event-Based Communication using custom events with promise-based responses. Both approaches provide the same functionality with different implementation styles, allowing developers to programmatically control dashboard behavior (such as applying filters, switching versions, or triggering downloads) from their host application and integrate dashboard actions into their own UI workflows or automation scripts.

setUserFilters Method​

Applies a set of filters to the widget’s current view. Useful for programmatically controlling the data display.

Syntax:

// Enables changes to the userFilters property.
const dashboardComponent = document.querySelector("qrvey-dashboard");
dashboardComponent.setUserFilters(filters);

Note: For parameter type filters see Working With Filters in Embedded Scenarios.

executeAction Method​

The executeAction method provides direct access to dashboard functionality through method calls on the dashboard element.

Syntax:

dashboard.executeAction(actionName, parameters)
  .then(response => {
    // Handle success
  })
  .catch(error => {
    // Handle error
  });

executeAction("atApplyUserFilters")​

Applies user-defined filters to the dashboard data. This allows you to programmatically filter dashboard content based on specific criteria.

Applicable Views: Preview, Design and Interact

PropertyTypeRequired
filtersIFBUserFilters. For details about the filter object see Working With Filters in Embedded Scenarios.Required
const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('atApplyUserFilters', {
  filters: [
    {
      operator: 'AND',
      expressions: [
        {
          qrveyid: 'syqssyvbr',
          questionid: 'f4koA2I1b',
          validationType: 'EQUAL',
          value: ['0 - 1 Solar Resource Assessment']
        }
      ]
    }
  ]
})
.then(result => console.log('Filters applied successfully:', result))
.catch(error => console.error('Failed to apply filters:', error));

executeAction("qvDSHRestoreDashboard")​

Switches between different versions of the dashboard, allowing users to restore original, personalized, or handle non-existent versions.

Applicable Views: Interact

PropertyTypeRequired
versionString. One of ORIGINAL, PERSONALIZED or NO-VERSION-EXISTSRequired
const dashboard = document.querySelector('qrvey-dashboard');

// Restore original version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'ORIGINAL' })
  .then(result => console.log('Original version restored'))
  .catch(error => console.error('Failed to restore version:', error));

// Restore personalized version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'PERSONALIZED' })
  .then(result => console.log('Personalized version restored'))
  .catch(error => console.error('Failed to restore version:', error));

// Handle non-existent version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'NO-VERSION-EXISTS' })
  .then(result => console.log('Version handling completed'))
  .catch(error => console.error('Version does not exist:', error));

executeAction("qvDSHSaveDashboard")​

Saves (interact mode) or publishes (design mode) the current state of the dashboard, persisting any changes made by the user.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHSaveDashboard')
  .then(result => console.log('Dashboard saved successfully:', result))
  .catch(error => console.error('Failed to save dashboard:', error));

executeAction("qvDSHDownloadDashboard")​

Triggers a download of the dashboard, opening the modal to configure the download or to schedule a report/export file. The format attribute is required for the download.

Applicable Views: Design and Interact

PropertyTypeRequired
formatString. One of PDF, CSV, EXCEL or DATASETRequired
const dashboard = document.querySelector('qrvey-dashboard');

// Download as PDF
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'PDF' })
  .then(result => console.log('PDF download initiated'))
  .catch(error => console.error('PDF download failed:', error));

// Download as CSV
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'CSV' })
  .then(result => console.log('CSV download initiated'))
  .catch(error => console.error('CSV download failed:', error));

// Download as Excel
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'EXCEL' })
  .then(result => console.log('Excel download initiated'))
  .catch(error => console.error('Excel download failed:', error));

// Download as Dataset
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'DATASET' })
  .then(result => console.log('Dataset download initiated'))
  .catch(error => console.error('Dataset download failed:', error));

executeAction("qvDSHUndo")​

Reverts the last action performed on the dashboard, allowing users to step back through their changes.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHUndo')
  .then(result => console.log('Last action undone:', result))
  .catch(error => console.error('Undo failed:', error));

executeAction("qvDSHRedo")​

Reapplies a previously undone action, allowing users to step forward through their change history.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHRedo')
  .then(result => console.log('Action redone:', result))
  .catch(error => console.error('Redo failed:', error));

executeAction("qvDSHDiscardChanges")​

Discards all unsaved changes made to the dashboard, reverting it to its last saved state.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHDiscardChanges')
  .then(result => console.log('Changes discarded:', result))
  .catch(error => console.error('Failed to discard changes:', error));

executeAction("qvDSHHiddenItems")​

Opens the hidden items panel, allowing users to view and potentially restore previously hidden dashboard elements.

Applicable Views: Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHHiddenItems')
  .then(result => console.log('Hidden items panel opened:', result))
  .catch(error => console.error('Failed to open hidden items:', error));

Incoming Events (Custom Events Listened By Widget)​

The dashboard supports event-based communication using custom events. You can dispatch events directly and handle them however you prefer. However, if you need a response from the dashboard, you can listen for a result event with the same name plus a Result suffix (for example, dispatching qvDSHSaveDashboard and listening for qvDSHSaveDashboardResult). The following helper function demonstrates this pattern with promise-based handling, but you can implement your own event-handling approach.

Helper Function:

function dispatchWithResponse(eventName, detail) {
  return new Promise((resolve, reject) => {
    const resultEvent = `${eventName}Result`;
    const onResult = (event) => {
      event.detail.success 
        ? resolve(event.detail.data) 
        : reject(new Error(event.detail.error));
      document.removeEventListener(resultEvent, onResult);
    };
    document.addEventListener(resultEvent, onResult);
    document.dispatchEvent(new CustomEvent(eventName, { detail }));
  });
}

// Usage wrapper
function callDispatch(eventName, detail={}) {
  dispatchWithResponse(eventName, detail)
    .then(res => console.log(`[Event] ${eventName} SUCCESS`, detail, res))
    .catch(err => console.log(`[Event] ${eventName} ERROR`, detail, err.message));
}

atApplyUserFilters​

Triggers the process of applying user filters to the dashboard, similar to method “apply-user-filters”

Applicable Views: Preview, Design and Interact

PropertyTypeRequired
filtersIFBUserFilters. For details about the filter object see Working With Filters in Embedded Scenarios.Required
dispatchWithResponse('atApplyUserFilters', {
  filters: [
    {
      operator: 'AND',
      expressions: [
        {
          qrveyid: 'syqssyvbr',
          questionid: 'f4koA2I1b',
          validationType: 'EQUAL',
          value: ['0 - 1 Solar Resource Assessment']
        }
      ]
    }
  ]
})
.then(result => console.log('Filters applied via event:', result))
.catch(error => console.error('Event-based filter application failed:', error));

qvDSHRestoreDashboard​

Requests the restoration of the dashboard to a previous saved state. Only the valid versions (ORIGINAL or PERSONALIZED) are allowed.

Applicable Views: Interact

PropertyTypeRequired
versionString. Either 'ORIGINAL''PERSONALIZED'
// Restore original version
dispatchWithResponse('qvDSHRestoreDashboard', { version: 'ORIGINAL' })
  .then(result => console.log('Original version restored via event'))
  .catch(error => console.error('Event-based restore failed:', error));

// Restore personalized version
dispatchWithResponse('qvDSHRestoreDashboard', { version: 'PERSONALIZED' })
  .then(result => console.log('Personalized version restored via event'))
  .catch(error => console.error('Event-based restore failed:', error));

qvDSHSaveDashboard​

Initiates the dashboard save operation, persisting all current modifications.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHSaveDashboard')
  .then(result => console.log('Dashboard saved via event:', result))
  .catch(error => console.error('Event-based save failed:', error));

qvDSHDownloadDashboard​

Triggers a download of the dashboard, opening the modal to configure the download or schedule, usually as a report or export file. The format attribute is required for the download.

Applicable Views: Design and Interact

PropertyTypeRequired
formatString. One of PDF, CSV, EXCEL. DATASET or JSONRequired
// Download as PDF via event
dispatchWithResponse('qvDSHDownloadDashboard', { format: 'PDF' })
  .then(result => console.log('PDF download initiated via event'))
  .catch(error => console.error('Event-based PDF download failed:', error));

// Download as CSV via event
dispatchWithResponse('qvDSHDownloadDashboard', { format: 'CSV' })
  .then(result => console.log('CSV download initiated via event'))
  .catch(error => console.error('Event-based CSV download failed:', error));

qvDSHUndo​

Triggers the undo operation for the most recent dashboard action.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHUndo')
  .then(result => console.log('Last action undone via event:', result))
  .catch(error => console.error('Event-based undo failed:', error));

qvDSHRedo​

Triggers the redo operation for the most recently undone action.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHRedo')
  .then(result => console.log('Action redone via event:', result))
  .catch(error => console.error('Event-based redo failed:', error));

qvDSHDiscardChanges​

Requests to discard all pending modifications to the dashboard.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHDiscardChanges')
  .then(result => console.log('Changes discarded via event:', result))
  .catch(error => console.error('Event-based discard failed:', error));

qvDSHHiddenItems​

Opens the hidden elements modal where deleted dashboard items can be reviewed or restored.

Applicable Views: Interact

dispatchWithResponse('qvDSHHiddenItems')
  .then(result => console.log('Hidden items panel opened via event:', result))
  .catch(error => console.error('Event-based hidden items failed:', error));

Outgoing Events (Custom Events Emitted By Widget)​

This section describes the custom DOM events emitted by the dashboard widget. These events notify your host application about important actions or state changes within the dashboard, such as when a page loads, filters are applied, or a download completes. Listen for these events to react to dashboard activity, update your UI, or trigger additional logic in your application.

qvDSHPageLoaded​

Emitted when the dashboard page has fully loaded and is ready for interaction.

Applicable Views: Preview, Design and Interact

document.addEventListener('qvDSHPageLoaded', (event) => {
  console.log('Dashboard page loaded and ready');
  // Initialize any dashboard-dependent functionality here
});

qvDSHItemsLoaded​

Emitted once all visible dashboard items (panels) have been successfully loaded.

Applicable Views: Preview, Design and Interact

document.addEventListener('qvDSHItemsLoaded', (event) => {
  console.log('Dashboard items loaded successfully');
  // Perform actions that depend on dashboard items being available
});

qvDSHHiddenItemsResult​

Emitted when the hidden items modal has been opened

Applicable Views: Interact

document.addEventListener('qvDSHHiddenItemsResult', (event) => {
  console.log('Hidden items result:', event.detail);
  if (event.detail.success) {
    console.log('Hidden items accessed successfully');
  } else {
    console.error('Error accessing hidden items:', event.detail.error);
  }
});

Error Handling​

Both direct method calls and event-based communication provide comprehensive error handling:

  • Success responses contain the operation result data
  • Error responses include detailed error information
  • Network or system errors are caught and can be handled appropriately

Always implement proper error handling to ensure a robust user experience:

// Example with comprehensive error handling
dashboard.executeAction('download', { format: 'PDF' })
  .then(result => {
    console.log('Download successful:', result);
    // Handle successful download
  })
  .catch(error => {
    if (error.response) {
      console.error('Server error:', error.response);
      // Handle server-side errors
    } else {
      console.error('Client error:', error.message);
      // Handle client-side errors
    }
  });

Event Modes​

Some events are only fired in specific widget modes (Design, Interaction, Preview). Refer to the event documentation for mode-specific details.